home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1996 January / macformat-033.iso / mac / Shareware City / Control Strip / ES 1.0 Package / Programming Stuff / ExtensionsStrip.h next >
Encoding:
C/C++ Source or Header  |  1995-10-17  |  16.6 KB  |  418 lines  |  [TEXT/MMCC]
  1. /*
  2.      File:        ExtensionsStrip.h
  3.  
  4.      Contains:    Extensions Strip Specific Interfaces plus the commented out
  5.                  Universal ControlStrip.h Interfaces.
  6.  
  7.      Version:    Technology:    System 7.1+ (System 7.5+ preferred)
  8.                  Package:    Extensions Strip 1.0
  9.  
  10.      Copyright:    © 1995 by Ammon Skidmore, Skidperfect Software Inc.
  11.                  All rights reserved.
  12.  
  13.      Bugs?:        If you find a problem, or have a criticism (they are welcome)
  14.                  with this file, please inform the author at the following address:
  15.                      Internet:    skidperfect@kagi.com
  16. */
  17.  
  18. #ifndef __EXTENSIONSSTRIP__
  19. #define __EXTENSIONSSTRIP__
  20.  
  21. #ifndef __CONTROLSTRIP__
  22. #include <ControlStrip.h>
  23. #endif
  24.  
  25. #ifndef __APPLEEVENTS__
  26. #include <AppleEvents.h>
  27. #endif
  28.  
  29. #ifdef __cplusplus
  30. extern "C" {
  31. #endif
  32.  
  33. #if PRAGMA_ALIGN_SUPPORTED
  34. #pragma options align=mac68k
  35. #endif
  36.  
  37. #if PRAGMA_IMPORT_SUPPORTED
  38. #pragma import on
  39. #endif
  40.  
  41.  
  42. /*********************************************************************************************
  43.  
  44.     Selector calls to the module.
  45.  
  46. *********************************************************************************************/
  47. enum {
  48. //    sdevInitModule                = 0,    /* initialize the module */
  49. //    sdevCloseModule                = 1,    /* clean up before being closed */
  50. //    sdevFeatures                = 2,    /* return feature bits */
  51. //    sdevGetDisplayWidth            = 3,    /* returns the width of the module's display */
  52. //    sdevPeriodicTickle            = 4,    /* periodic tickle when nothing else is happening */
  53.                                         /* NB: you can return the special result values. */
  54. //    sdevDrawStatus                = 5,    /* update the interface in the Control Strip*/
  55. //    sdevMouseClick                = 6,    /* user clicked on the module's display area in the Control Strip */
  56.                                         /* NB: you can return the special result values. */
  57. //    sdevSaveSettings            = 7,    /* saved any changed settings in module's preferences file */
  58. //    sdevShowBalloonHelp            = 8,    /* puts up a help balloon, if the module has one to display */
  59.  
  60.     sdevInAppContext            = 2000,    /* called only once after the module specifically
  61.                                            requested to be executed from inside Extension
  62.                                            Strip's context. NB: you can return the special
  63.                                            result values. */
  64.  
  65.     sdevInterceptedEvent        = 2001,    /* if the module returned the sdevInterceptAllEvents
  66.                                            flag in its features, then this selector
  67.                                            will get called before _each_ event is processed
  68.                                            by Extensions Strip.  Meant to be used with
  69.                                            _SBGetCurrentEvent so each event can be looked at,
  70.                                            and modified if necessary (to prevent passing.)
  71.                                            NB: you can return the special result values. */
  72.  
  73.     sdevDragAccept                = 2002,    /* return 0 if you accept the current drag, and
  74.                                            1 if you do not.  Modules that do not have any
  75.                                            drag handlers will never get this called.
  76.                                            NB: sdevDragAccept is only called from within
  77.                                            Extensions Strip's dragTrackingInWindow.  So it
  78.                                            is recommended to only check if you accept the drag
  79.                                            from within your dragTrackingEnterWindow, and then
  80.                                            set a global var that you can pass onto ES. */
  81.  
  82.     sdevEventMask                = 2003    /* if the module returned the sdevInterceptAllEvents
  83.                                            flag in its features, this selector will get
  84.                                            called to find the event mask to use.  Return your
  85.                                            mask as the result value of the sdev call.
  86.                                            sdevEventMask is called once upon initialization,
  87.                                            and every time sdevFeaturesChange is requested. */
  88. };
  89.  
  90. /*********************************************************************************************
  91.  
  92.     Features supported by the module.  If a bit is set, it means that feature is supported.
  93.     All undefined bits are reserved for future use by Apple, and should be set to zero.
  94.  
  95. *********************************************************************************************/
  96. /*
  97.     Tip: if you clear sdevWantMouseClicks and set sdevDontAutoTrack, your module
  98.     will receive clicks and Extensions Strip (plus Desktop Strip) will not
  99.     auto-hilite your module.
  100. */
  101. enum {
  102. //    sdevWantMouseClicks            = 0,    /* notify the module of mouseDown events */
  103. //    sdevDontAutoTrack            = 1,    /* call the module to do mouse tracking  */
  104. //    sdevHasCustomHelp            = 2,    /* module provides its own help messages */
  105. //    sdevKeepModuleLocked        = 3,    /* module needs to be locked in the heap */
  106.  
  107.     sdevHasDragHandlers            = 31,    /* module has installed a drag tracking and/or
  108.                                            receive handler in the Strip window. */
  109.  
  110.     sdevDontPeriodicTickle        = 30,    /* module does not require any idle time so
  111.                                            by setting this bit it will never get
  112.                                            called with the sdevPeriodicTickle 
  113.                                            selector.  Note that you can set this along
  114.                                            with the sdevInterceptAllEvents bit (if you want)
  115.                                            and sdevInterceptedEvent will still get called.
  116.                                            So be nice and set this to help speed up idle
  117.                                            time processing. */
  118.  
  119.     sdevInterceptAllEvents        = 29    /* module wants to be executed before each
  120.                                            event passes through Extension Strip's
  121.                                            jGNE filter.  Because the module is allowed
  122.                                            to modify every event, there is no more need
  123.                                            for modules, such as Terminator Strip, to
  124.                                            install their own jGNE filters!
  125.                                            NB: You need to return an event mask when your
  126.                                            module is called by the sdevEventMask selector. */
  127. };
  128.  
  129. /*********************************************************************************************
  130.  
  131.     Special result values returned by the sdevPeriodicTickle and sdevMouseClick selectors.
  132.     If a bit is set, the module can request that a specific function is performed by
  133.     the Control Strip.  A result of zero will do nothing.  All undefined bits are reserved
  134.     for future use by Apple, and should be set to zero.
  135.  
  136. *********************************************************************************************/
  137. /*
  138.     Note: these values can also be returned by the sdevInAppContext and
  139.     sdevInterceptedEvent selectors.
  140. */
  141. enum {
  142. //    sdevResizeDisplay            = 0,    /* resize the module's display */
  143. //    sdevNeedToSave                = 1,    /* need to save changed settings, when convenient */
  144. //    sdevHelpStateChange            = 2,    /* need to update the help message because of a state change */
  145. //    sdevCloseNow                = 3,    /* close a module because it doesn't want to stay around */
  146.  
  147.     sdevQueueModule                = 31,    /* module needs to be executed from within
  148.                                            Extension Strip's context: useful for
  149.                                            things like sending AppleEvents or
  150.                                            creating and tracking new drags. */
  151.  
  152.     sdevFeaturesChange            = 30    /* module wants to change its feature flags. Useful
  153.                                            for changing clickable state of the module and
  154.                                            for locking/unlocking the sdev code. */
  155. };
  156.  
  157. /*********************************************************************************************
  158.  
  159.     miscellaneous
  160.  
  161. *********************************************************************************************/
  162. enum {
  163. //    sdevFileType                    = 'sdev',    /* module file and code resource type */
  164.     sdevTypeCodePPC                    = 'Sdev'    /* resource type for module's PPC code */
  165. };
  166.  
  167. //
  168.  
  169. //enum {
  170. //    sdevMenuItemMark            = '•'
  171. //};
  172.  
  173. /*    direction values for SBDrawBarGraph*/
  174. //enum {
  175. //    BarGraphSlopeLeft            = -1,                            /* max end of sloping bar graph is on the left*/
  176. //    BarGraphFlatRight            = 0,                            /* max end of flat bar graph is on the right*/
  177. //    BarGraphSlopeRight            = 1                                /* max end of sloping bar graph is on the right*/
  178. //};
  179.  
  180. //
  181.  
  182. enum {
  183.     //
  184.     gestaltExtensionsStripAttr        = 'CsEs',    /* returns Extensions Strip's attributes */
  185.     
  186.     /* currently returned bits from gestaltExtensionsStripAttr: */
  187.     gestaltExtensionsStripExists    = 0,        /* Extensions Strip is currently launched */
  188.  
  189.     
  190.     //
  191.     gestaltDesktopStripAttr            = 'CsWT'    /* returns the Mice and Men's Desktop Strip
  192.                                                    attributes which are supported by
  193.                                                    Extensions Strip.  See Desktop Strip's
  194.                                                    documentation for details about the bits */
  195. };
  196.  
  197. //
  198.  
  199. typedef unsigned long ModuleReference;
  200.  
  201. //
  202.  
  203. typedef pascal void (*SBQueueProcPtr)(unsigned long refCon);
  204.  
  205. #if GENERATINGCFM
  206. typedef UniversalProcPtr SBQueueUPP;
  207. #else
  208. typedef SBQueueProcPtr SBQueueUPP;
  209. #endif
  210.  
  211. enum {
  212.     uppQueueProcProcInfo = kPascalStackBased | STACK_ROUTINE_PARAMETER(1, kFourByteCode)
  213. };
  214.  
  215. #if GENERATINGCFM
  216. #define NewSBQueueProcProc(userRoutine)        \
  217.         (SBQueueUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppAEIdleProcInfo, GetCurrentArchitecture())
  218. #else
  219. #define NewSBQueueProcProc(userRoutine)        \
  220.         ((SBQueueUPP) (userRoutine))
  221. #endif
  222.  
  223. //
  224.  
  225. /*********************************************************************************************
  226.  
  227.     utility routines to provide standard interface elements and support for common functions
  228.  
  229. *********************************************************************************************/
  230.  
  231. //                                                                                 //
  232. //                                                                                 //
  233. // All routines are documented as to whether the Extensions Strip implementation //
  234. // of them they may move memory.  You can trust that a routine that says it         //
  235. // will not move memory in this version, will not move memory in future versions.//
  236. // Note though, that some Universal Control Strip traps may move memory under     //
  237. // Control/Desktop Strip but not in Extensions Strip (such as                     //
  238. // _SBIsControlStripVisible and _SBShowHideControlStrip.)                         //
  239. //                                                                                 //
  240. //                                                                                 //
  241.  
  242. // =========================================================
  243. // ========== Universal Control Strip traps ================
  244. // =========================================================
  245. /*
  246.             // Will not move memory. //
  247. extern pascal Boolean SBIsControlStripVisible(void)
  248.  TWOWORDINLINE(0x7000, 0xAAF2);
  249.  
  250.             // Will not move memory. //
  251. extern pascal void SBShowHideControlStrip(Boolean showIt)
  252.  THREEWORDINLINE(0x303C, 0x0101, 0xAAF2);
  253.  
  254.             // Will not move memory. //
  255. extern pascal Boolean SBSafeToAccessStartupDisk(void)
  256.  TWOWORDINLINE(0x7002, 0xAAF2);
  257.  
  258.             // May move memory! //
  259. extern pascal short SBOpenModuleResourceFile(OSType fileCreator)
  260.  THREEWORDINLINE(0x303C, 0x0203, 0xAAF2);
  261.  
  262.             // May move memory! //
  263. extern pascal OSErr SBLoadPreferences(ConstStr255Param prefsResourceName, Handle *preferences)
  264.  THREEWORDINLINE(0x303C, 0x0404, 0xAAF2);
  265.  
  266.             // May move memory! //
  267. extern pascal OSErr SBSavePreferences(ConstStr255Param prefsResourceName, Handle preferences)
  268.  THREEWORDINLINE(0x303C, 0x0405, 0xAAF2);
  269.  
  270.             // Will not move memory. //
  271. extern pascal void SBGetDetachedIndString(StringPtr theString, Handle stringList, short whichString)
  272.  THREEWORDINLINE(0x303C, 0x0506, 0xAAF2);
  273.  
  274.             // May move memory! //
  275. extern pascal OSErr SBGetDetachIconSuite(Handle *theIconSuite, short theResID, unsigned long selector)
  276.  THREEWORDINLINE(0x303C, 0x0507, 0xAAF2);
  277.  
  278.             // May move memory! //
  279. extern pascal OSErr SBTrackPopupMenu(const Rect *moduleRect, MenuHandle theMenu)
  280.  THREEWORDINLINE(0x303C, 0x0408, 0xAAF2);
  281.  
  282.             // May move memory! //
  283. extern pascal OSErr SBTrackSlider(const Rect *moduleRect, short ticksOnSlider, short initialValue)
  284.  THREEWORDINLINE(0x303C, 0x0409, 0xAAF2);
  285.  
  286.             // May move memory! //
  287. extern pascal OSErr SBShowHelpString(const Rect *moduleRect, StringPtr helpString)
  288.  THREEWORDINLINE(0x303C, 0x040A, 0xAAF2);
  289.  
  290.             // Will not move memory. //
  291. extern pascal short SBGetBarGraphWidth(short barCount)
  292.  THREEWORDINLINE(0x303C, 0x010B, 0xAAF2);
  293.  
  294.             // May move memory! //
  295. extern pascal void SBDrawBarGraph(short level, short barCount, short direction, Point barGraphTopLeft)
  296.  THREEWORDINLINE(0x303C, 0x050C, 0xAAF2);
  297.  
  298.             // May move memory! //
  299. extern pascal void SBModalDialogInContext(ModalFilterUPP filterProc, short *itemHit)
  300.  THREEWORDINLINE(0x303C, 0x040D, 0xAAF2);
  301. */
  302.  
  303. // =======================================================
  304. // ========== Extensions Strip ONLY traps ================
  305. // =======================================================
  306.  
  307. /* Strip Window Utilities */
  308.  
  309.     // returns: true = vertical; false = horizontal
  310.     //        // Will not move memory. //
  311. extern pascal Boolean SBIsControlStripVertical(WindowRef stripPort)
  312.  TWOWORDINLINE(0x70FF, 0xAAF2);
  313.  
  314.     // returns pixel depth of the monitor this Strip window is in (always a power of 2)
  315.     //        // Will not move memory. //
  316. extern pascal short SBGetControlStripDepth(WindowRef stripPort)
  317.  TWOWORDINLINE(0x70FE, 0xAAF2);
  318.  
  319.     // returns the current normal back color of this Strip window
  320.     //        // Will not move memory. //
  321. extern pascal void SBGetStripBackColor(RGBColor *color, WindowRef stripPort)
  322.  TWOWORDINLINE(0x70FD, 0xAAF2);
  323.  
  324.     //returns the current back color of this Strip window when a module is selected
  325.     //        // Will not move memory. //
  326. extern pascal void SBGetStripSelectedColor(RGBColor *color, WindowRef stripPort)
  327.  TWOWORDINLINE(0x70FC, 0xAAF2);
  328.  
  329. /* Module Utilities */
  330.  
  331.     // returns a reference number that all of the Module Utilities need
  332.         /* NB: since SBGetMyReferenceNum can ONLY be called from sdevInitModule,
  333.            you should save its value into your globals if you are going to use
  334.            one of the Module Utilities later, such as inside a tracking handler. */
  335.     // Also, the reference number will always be non-zero.
  336.     //        // Will not move memory. //
  337. extern pascal ModuleReference SBGetMyReferenceNum(void)
  338.  TWOWORDINLINE(0x70FB, 0xAAF2);
  339.  
  340.     // total window space taken up by a module.  Useful for drag-n-drop calculations
  341.     // note that this rect will always be larger than the module's statusRect.
  342.     //        // Will not move memory. //
  343. extern pascal void SBGetTotalModuleBounds(Rect *bounds, WindowRef stripPort, ModuleReference moduleRefNum)
  344.  TWOWORDINLINE(0x70FA, 0xAAF2);
  345.  
  346.     // returns the statusRect of the module.  Very useful for drag-n-drop routines
  347.     // because you no longer have to constantly set a global rectangle variable to
  348.     // hold the current location of the module in the Strip window.
  349.     //        // Will not move memory. //
  350. extern pascal void SBGetModuleBounds(Rect *bounds, ModuleReference moduleRefNum)
  351.  TWOWORDINLINE(0x70F9, 0xAAF2);
  352.  
  353. /* Miscellaneous Utilities */
  354.  
  355.     // runs this (locked!) piece of code once within Extensions Strip's context.
  356.     // PPC modules must pass a valid routine descriptor to this function.  Since
  357.     // the descriptor will not be disposed of after the code has executed, I would
  358.     // recommend creating the descriptor (NewSBQueueProcProc) when sdevInitModule
  359.     // is called and disposing it upon sdevCloseModule.
  360.     // A non-zero result code means that the UPP could not be queued (memory error).
  361.     //        // May move memory! //
  362. extern pascal OSErr SBQueueCode(SBQueueUPP theProc, unsigned long refCon)
  363.  TWOWORDINLINE(0x70F8, 0xAAF2);
  364.  
  365.     // sends the specified Apple Event within Extensions Strip's context to insure
  366.     // safe sending rather than trusting that the front application is AE aware.
  367.     // _SBSimpleAESend acts just like _AESend in that the AppleEvent you give to it
  368.     // must still be disposed of afterward by your code to free up memory (even
  369.     // though the event hasn't actually been sent yet.)
  370.     //
  371.     // _SBSimpleAESend is meant to be an easy way to send simple events.  If you
  372.     // need to check the reply AppleEvent or the _AESend error, ect., you should queue
  373.     // your code (with _SBQueueCode or by having your module return 'sdevQueueModule')
  374.     // and send the Apple Event yourself.  The result returned by _SBSimpleAESend
  375.     // is only non-zero if an error occured while queueing the event for later sending.
  376.     //
  377.     // Also, if an error does occur when Extensions Strip sends your AppleEvent, the
  378.     // user will be notified with a dialog that _AESend failed.
  379.     //
  380.     // Here are the parameters I give to _AESend.  They are basic enough for most
  381.     // kinds of Apple Events that modules send, hence the name _SBSimpleAESend.
  382.     // err = AESend(&theAppleEvent, &reply,                // your specified AppleEvent
  383.     //                                                    // and a dummy reply descriptor
  384.     //            kAENoReply + kAEAlwaysInteract + kAECanSwitchLayer,    // send mode
  385.     //            kAENormalPriority,                                    // send priority
  386.     //            kAEDefaultTimeout,                                    // time out
  387.     //            nil,                                                // idleProc
  388.     //            nil);                                                // filterProc
  389.     //        // May move memory! //
  390. extern pascal OSErr SBSimpleAESend(const AppleEvent *theAppleEvent)
  391.  TWOWORDINLINE(0x70F7, 0xAAF2);
  392.  
  393.     // returns a pointer to the current event being processed.  Modififations to
  394.     // the data in this pointer WILL take effect as the event gets passed along
  395.     // to the other processes and jGNE filters further on in the chain.  Although
  396.     // a module can use this function at any time, it is really meant to be called
  397.     // within the sdevInterceptedEvent selector because this is where a module can
  398.     // deny other modules the proper processing of the event (such as in the case
  399.     // of a keyDown.)  Another good use for SBGetCurrentEvent() is to find the exact
  400.     // point where a mouseDown occured if you have a queue of clickable objects.
  401.     //        // Will not move memory. //
  402. extern pascal EventRecord* SBGetCurrentEvent(void)
  403.  TWOWORDINLINE(0x70F6, 0xAAF2);
  404.  
  405.  
  406. #if PRAGMA_IMPORT_SUPPORTED
  407. #pragma import off
  408. #endif
  409.  
  410. #if PRAGMA_ALIGN_SUPPORTED
  411. #pragma options align=reset
  412. #endif
  413.  
  414. #ifdef __cplusplus
  415. }
  416. #endif
  417.  
  418. #endif /* __EXTENSIONSSTRIP__ */